When if ever should we describe browser bugs/support differences in MDN content pages, rather than just leave them in BCD?

[wbamberg]

This is a slightly-cleaned-up version of a discussion thread in Slack. I'm not really sure what to make of it yet, so I'm mostly sticking this here before Slack eats it, although it would be good to try to make a proper guideline out of it at some point so people like me stop asking.

Original question

Recurring question: when should/shouldn't we describe browser bugs/support differences in MDN content pages, rather than just leave them in BCD? We usually say "document the spec and leave browser differences to BCD" but it bothers me that this isn't very helpful, partly because BCD - as it is rendered in MDN pages - isn't great at surfacing these differences, and partly because BCD doesn't have a very rich language for expressing them. So from a usability pov I'm always drawn to document them in the page. The case at hand is mdn/content#38132 , which seems to want to capture a Safari bug (https://bugs.webkit.org/show_bug.cgi?id=77998). I'm tempted to include this in the page, for the reasons above (I don't think the current wording on the PR is ideal, but that's a separate question). I think we should also document the bug in BCD. But should we only document it there?

@Josh-Cena

I think in this case we should move their second paragraph to BCD, since it's literally just "affected by zoom".
However a content note is also necessary for the first paragraph, saying what the expected interaction with zoom is, with a note saying "some browsers are not conformant; check the BCD".

Something like:

The returned rectangle is scaled according to any transformation that affects the rendered size, including page zooming effects, CSS zoom, transform, etc. However, some browsers may behave differently. See browser compatibility for details.

Because I know as a fact that devicePixelRatio also interacts badly with page zooming on Safari—in which case https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio mentions the typical zooming interaction, and BCD notes Safari as partial implementation. I'm happy to drop the "browsers are incompatible" note in content, but what's expected should be documented.

@hamishwillee

FWIW

• No, it isn't particularly helpful
• In reference we document the spec, with the exception of a "defacto standard".
• Any other approach is maintainable [ed: I think this should be "unmaintainable"] - I still sometimes run into in-docs-compat notes that are probably incorrect, but certainly unverifiable.
• It is reasonable to highlight that a particular version might have serious incompatibilities.
• I very much like the separation of incompatibility and browser specifics into the compatibility section.
• I'm OK with that section being extended in specific cases with hand-crafted text where the BCD information is not sufficient.

Upshot I'd rather use the tools we have and be accurate than attempt to integrate in the body of text.

@OnkarRuikar

Documenting browser bugs in content doesn't sound good. Shifts focus away from the main content. If it is a bug, we could add the bug link to the 'See also' section, with one liner, instead of a big para in the content. This will save us from future corrections in the page content. When people will follow the bug link they'll know if the bug has been fixed or not.
If the bug doesn't exit on browser sites then we can ask the pr author to report there and provide a link. Or we could report the bug ourselves and update the PR if it's a really a bug.

@captainbrosset

I know this is quite tricky, but I tend to agree with Will. Documenting spec only means documenting what we want the platform to be, not what it currently is.
Documenting the real state of things is much harder to maintain/validate. But if we can keep it up to date, then is also vastly more useful to web developers. The right thing to do is probably in the middle somewhere, and I think that's what MDN already does. For example, the docs for customizable built-in elements has a banner saying that Safari won't implement it. That's not spec, that's browser reality. Case by case banners like this make sense to me. I wouldn't want to have to read an entire MDN page, familiarizing me with a technology, following syntax and examples, only to find out later that I can't use it cause it's not really implemented as described in all browsers.

I think web-features/baseline should help here. Ideally, BCD would help, and it already has the structured data for it. But BCD makes no decision as to what's blocking or not blocking. While web-features does. Web-features takes one or more BCD keys, groups them into a feature that makes sense to developers, and then makes a (possibly manual/editorial) decision as to whether the feature is supported or not, and where. So I guess what I'm saying is:

• for maintainability reasons, let's keep content mostly focused on spec (with the exception of de-facto standards and special cases like is)
• improve web-features to make it surface blocking bugs more prominently

@Josh-Cena again

In case my opinion wasn't clear:

• Guiding principle is, do not name browsers in content, and do not provide any information that's temporary, unless for really, really important caveats (usual browser bugs would not be mentioned at all)
• Exception: if the browser's decision is permanent, like is, or other non-standard thing a browser explicitly chooses to do
• However, do remind readers to check BCD, in case the content describes some behavior that's not implemented by a browser that's beyond just the lack of availability
• In this case: we should document the typical interaction of scaling with client rects, as that's an important gotcha. Therefore by the previous principle we should mention some browsers not implementing it, just to preempt common reader questions.

I think window.devicePixelRatio is a good model to follow.

[OnkarRuikar]

If a feature has 10 bugs in different browsers, then the page would look more like a bug report than a feature page.
We could create a separate ## Caveats and bugs section or use the existing ## See also. Readers will get accustomed to looking for such a section where they can find all the feature related issues on the page.

[bsmth]

I do also like @captainbrosset's point about documenting the real state of things. I wonder if there's any appetite for footnotes or annotations that link to a section like this (## Browser bugs / known issues).

edit: i.e., some other mechanism that's not as interleaved with content as "this is the feature, this browser handles is this way, the other browser has it behind a flag" - if there was a way to display this information by means of annotations, that could be filtered out / updated via automation without prose rewrites, it would be nice.

[hamishwillee]

Obviously interleaved comments right where the incompatibility happens would be more useful for readers but we know this is unmaintainable. I hadn't considered a footnote solution linking to a section on issues. That at least might be maintainable because all the differences are in one section.

If it were me, such a section would be inside compatibility section. We would need to consider disclaimers, dates, bug links and other tricks to give hints when the material needs to be revisited.

[wbamberg]

If it were me, such a section would be inside compatibility section.

Yes, this is surely the right place to keep it (if we want it in content at all, that is).

[bsmth]

Just for the sake of illustration, this is the footnote support in GFM (docs/blog):

Browser-specific settings are enabled, such as blocking all cookies, private browsing mode[^1], automatic cookie deletion on close, etc.
 
## Browser compatibility
 
{{compat}}
 
[^1]: In Firefox, Service Worker APIs are hidden and cannot be used when the user is in [private browsing mode](https://bugzil.la/1320796), or when history is disabled, or if cookies are cleared when Firefox is closed.

i.e.;

Browser-specific settings are enabled, such as blocking all cookies, private browsing mode¹, automatic cookie deletion on close, etc.

Browser compatibility

{{compat}}

Footnotes

1. In Firefox, Service Worker APIs are hidden and cannot be used when the user is in private browsing mode, or when history is disabled, or if cookies are cleared when Firefox is closed. ↩

[hamishwillee]

I quite like that. Even if we can do this though, we should still do it only where it really matters - and provide ourselves with enough hints/issue links etc to allow us to know when things have likely changed.